Contents

1 Preamble

1.1 Dependencies

library(ggplot2)
library(patchwork)
library(SpatialData)
library(SingleCellExperiment)

1.2 Introduction

2 SpatialData

The SpatialData class contains 5 elements that are represented as follows:

path <- system.file("extdata", "raccoon", package="SpatialData", mustWork=TRUE)
(spd <- readSpatialData(path))
## class: SpatialData
## table: 
## images(1): raccoon
## labels(1): segmentation
## shapes(1): circles
## points(0):
## coords(1): global

2.1 Accession

The following accessors are currently supported:

  • image/label/shape/pointNames to retrieve available entities of the respective element.
  • images/labels/shapes/points to retrieve a list of entities of the respective element.
  • image/label/shape/point to retrieve a single entity of the respective element.
  • $ to directly access the entities of the respective element.

SpatialData objects behave like a list, i.e., entities of a all elements can be accessed in various (equivalent) ways:

# these are all equivalent
i <- imageNames(spd)[1]
element(spd, "images", i)
images(spd)[[i]]
image(spd, i)
spd$images[[i]]

2.2 Elements

The ZarrArray class is essentially an Annotated array-like object, that may contain a dense array or any type of Array (e.g., Sparse/DelayedArray). Derived here-from are the ImageArray and LabelArray classes that represent single entities of images and labels, respectively. These differ slightly in their associated metadata and array properties, but share many functions.

# extract 'ImageArray'
img <- image(spd, i)
# rename channels
channels(img) <- c("R", "G", "B")
img
## class: ImageArray
## channels: R G B 
## axiis(): 3 768 1024 
## |-time(0): 
## |-space(0): 
## |-channel(0): 
## coords(1): global

Shapes are represented as ShapeFrames. Currently, these support shapes of type circle and polygon. Under the hood, these are just DataFrames (with specialized methods and additional internal requirements):

(s <- shape(spd))
## class: ShapeFrame
## geoms: 4 
## type: circle 
## coords(1): global
DataFrame(s)
## DataFrame with 4 rows and 4 columns
##          data   index  radius        type
##       <array> <array> <array> <character>
## 1 c(610, 450)       0      30      circle
## 2 c(730, 325)       1      30      circle
## 3 c(575, 300)       2      30      circle
## 4  c(480, 90)       3      50      circle

3 Transformations

Only translation, scaling, and rotation of Image/LabelArrays are currently supported via the following functions, each of which expects a object (SD), as well as transformation data t according to:

Available coordinate systems can be retrieved via coords():

coords(img)
##     input.axes input.name  output.axes output.name     type
## 1 c("c", "....        cyx c("c", "....      global identity

3.1 Translation

# move the raccoon up'n' down
ps <- lapply(c(-300, 0, 300), \(t) 
    translateElement(img, c(t, 0)))
wrap_plots(lapply(ps, plotElement))

3.2 Rotation

# spin the raccoon (anti-clockwise)
ps <- lapply(c(0, 30, 60), \(t) 
    rotateElement(img, t))
wrap_plots(lapply(ps, plotElement))

3.3 Scaling

# squeeze the raccoon horizontally
ps <- lapply(c(1, 2/3, 1/2), \(t) 
    scaleElement(img, c(1, 1, t)))
wrap_plots(lapply(ps, plotElement))

4 Visualization

4.1 By element

Element-wise plotting is possible via plotElement, which expects a single SpatialData element as input. Images and shapes are rendered via annotation_raster; for shapes (geom_polygon), additional graphical parameters may be passed as dot (...) arguments.

plotElement(image(spd)) +
plotElement(label(spd)) +
plotElement(shape(spd), col="blue", fill="cyan") 

4.2 Layered

plotSD currently supports overlaying arbitrary elements; currently, only one instance each is supported. Argument coord specifies the target coordinate system, and will default to the first available shared one if left unspecified. Elements are internally aligned via alignElements, which in turn calls transformArray on the input image and label (type Image/LabelArray). Depending on the underlying metadata, transformElement uses scale/rotate/translateElement for transformation.

# defaults to including all available elements
plotSD(spd,
    alpha.label=1/3,
    alpha.shape=1,
    fill.shape="lightgrey")

path <- system.file("extdata", "blobs", package="SpatialData", mustWork=TRUE)
(spd <- readSpatialData(path))
## class: SpatialData
## table: 3 26 
## images(1): blobs_image
## labels(1): blobs_labels
## shapes(1): blobs_shapes
## points(1): blobs_points
## coords(1): global
plotElement(image(spd)) +
plotElement(label(spd)) +
plotElement(shape(spd)) +
plotElement(point(spd))

plotSD(spd,
    alpha.label=1/3,
    alpha.shape=1,
    fill.shape="lightgrey")

5 Query

5.1 Aggregation

aggregateImage computed aggregated measurement values from image according to label using fun to summarized measurements (default mean). By default, the first available image and label are used. In the output SingleCellExperiment, rows correspond to channels and columns to unique labels (excluding 0); aggregated xy-coordinates are included in the colData.

(sce <- aggregateImage(spd))
## class: SingleCellExperiment 
## dim: 3 26 
## metadata(0):
## assays(1): mean
## rownames: NULL
## rowData names(0):
## colnames(26): 1 2 ... 29 30
## colData names(2): x y
## reducedDimNames(0):
## mainExpName: NULL
## altExpNames(0):

6 Appendix

6.1 Session info

sessionInfo()
## R version 4.3.0 (2023-04-21)
## Platform: aarch64-apple-darwin20 (64-bit)
## Running under: macOS Ventura 13.2.1
## 
## Matrix products: default
## BLAS:   /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRblas.0.dylib 
## LAPACK: /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.11.0
## 
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## time zone: Europe/Zurich
## tzcode source: internal
## 
## attached base packages:
## [1] stats    graphics utils    stats4   methods  base    
## 
## other attached packages:
##  [1] SingleCellExperiment_1.22.0 SummarizedExperiment_1.30.0
##  [3] Biobase_2.60.0              GenomicRanges_1.52.0       
##  [5] GenomeInfoDb_1.36.0         IRanges_2.34.0             
##  [7] S4Vectors_0.38.0            BiocGenerics_0.46.0        
##  [9] MatrixGenerics_1.12.0       matrixStats_0.63.0         
## [11] SpatialData_0.99.0          patchwork_1.1.2            
## [13] ggplot2_3.4.2               BiocStyle_2.28.0           
## 
## loaded via a namespace (and not attached):
##  [1] tidyselect_1.2.0        EBImage_4.42.0          farver_2.1.1           
##  [4] dplyr_1.1.2             filelock_1.0.2          arrow_11.0.0.3         
##  [7] R.utils_2.12.2          bitops_1.0-7            fastmap_1.1.1          
## [10] RCurl_1.98-1.12         digest_0.6.31           lifecycle_1.0.3        
## [13] paws.storage_0.2.0      magrittr_2.0.3          compiler_4.3.0         
## [16] rlang_1.1.1             sass_0.4.5              tools_4.3.0            
## [19] utf8_1.2.3              yaml_2.3.7              knitr_1.42             
## [22] labeling_0.4.2          S4Arrays_1.0.0          htmlwidgets_1.6.2      
## [25] bit_4.0.5               curl_5.0.0              here_1.0.1             
## [28] reticulate_1.28         DelayedArray_0.25.0     abind_1.4-5            
## [31] zellkonverter_1.10.0    withr_2.5.0             purrr_1.0.1            
## [34] R.oo_1.25.0             grid_4.3.0              fansi_1.0.4            
## [37] grDevices_4.3.0         colorspace_2.1-0        scales_1.2.1           
## [40] cli_3.6.1               rmarkdown_2.21          crayon_1.5.2           
## [43] generics_0.1.3          rstudioapi_0.14         httr_1.4.5             
## [46] cachem_1.0.7            stringr_1.5.0           zlibbioc_1.46.0        
## [49] datasets_4.3.0          parallel_4.3.0          assertthat_0.2.1       
## [52] BiocManager_1.30.20     XVector_0.40.0          tiff_0.1-11            
## [55] basilisk_1.11.2         vctrs_0.6.2             Matrix_1.5-4           
## [58] dir.expiry_1.8.0        jsonlite_1.8.4          bookdown_0.33          
## [61] fftwtools_0.9-11        bit64_4.0.5             magick_2.7.4           
## [64] jpeg_0.1-10             locfit_1.5-9.7          jquerylib_0.1.4        
## [67] glue_1.6.2              codetools_0.2-19        stringi_1.7.12         
## [70] gtable_0.3.3            Rarr_1.0.0              munsell_0.5.0          
## [73] tibble_3.2.1            pillar_1.9.0            basilisk.utils_1.12.0  
## [76] htmltools_0.5.5         GenomeInfoDbData_1.2.10 R6_2.5.1               
## [79] rprojroot_2.0.3         evaluate_0.20           lattice_0.21-8         
## [82] highr_0.10              R.methodsS3_1.8.2       png_0.1-8              
## [85] paws.common_0.5.6       bslib_0.4.2             Rcpp_1.0.10            
## [88] xfun_0.39               pkgconfig_2.0.3